docs(ui): state the type: 'form' action contract — in-shell, submit lands on the record (#7245) - #7417

Part of #7245 — the objectstack half only (the contract statement in hand-written docs). The renderer half lands in ObjectUI as a separate card, so this PR must not close the issue.

The ruling this implements

Maintainer ruling 2026-08-10 07:34Z on #7245, verbatim:

the type: 'form' contract means in-shell, and an internal submit lands on the record.

1. /forms/:name in mode="internal" nests inside the console shell (keep the route — deep-linking survives; the missing chrome is the defect, not the navigation).
2. Internal-mode submit defaults to redirect-to-created-record; thank-you stays the default for the public /f/:slug path only.
3. showcase_task.edit may declare a submitBehavior as an interim corpus fix, but the platform default is the ruling above — the corpus must not have to opt out of a wrong default.

What was measured first

Where the current prose describes type: 'form' / submitBehavior behavior, before writing anything:

Changes

• protocol/objectui/actions.mdx — new #### What type: 'form' promises subsection under Form Actions: renders in-shell (route kept, so deep-linking survives), internal submit defaults to redirect-to-created-record, explicit submitBehavior always wins; plus a public-vs-internal table (audience / chrome / default). The Action Types row gains the in-shell + lands-on-record clause.
• ui/forms.mdx — §8 drops the bare *(default)* marker from the kind table and gains a ### The default is mode-aware table (thank-you for public /console/f/:slug, redirect-to-created-record for internal /console/forms/:name, with the reason for each). §9 and the top-of-page bullet restate it and link the contract.
• ui/actions.mdx — form row links the contract.
• ui/public-data-collection.mdx — one paragraph: the explicit thank-you there is copy, not behavior, and the internal path defaults the other way.

Contract vs. shipped renderer — stated honestly, not documented as the contract

The console at the pinned .objectui-sha does not implement this yet (out-of-shell page, thank-you in both modes). Rather than documenting the defect, both pages carry a short dated "Current renderer status (2026-08-10)" note saying the renderer does not match yet, pointing at the ObjectUI half tracked from the #7245 thread, and telling authors to declare submitBehavior explicitly until it lands. Those notes come out when the renderer card lands.

Surface boundary — checked, and one out-of-surface flag

Generated content/docs/references/** and packages/spec/src/** were treated as out of surface. Measured whether the contract text is really spec-produced:

• submitBehavior is z.discriminatedUnion(...).optional().describe('Post-submit behavior') — the .describe() carries no default claim, and the generated content/docs/references/ui/view.mdx:269 reproduces exactly that neutral string. The schema has no .default(); the default is resolved by the renderer (FormPage's ?? { kind: 'thank-you' }).
• So the reader-facing producer of the "(default)" claim was the hand-written page, not the generated reference — this is a docs-surface change, not domain:spec-surface.
• ⚠️ Flag, not patched (out of surface): the source JSDoc above submitBehavior in packages/spec/src/ui/view.zod.ts (~line 2029) still says "thank-you (default) — show a confirmation panel". It is a source comment, not published to the docs site, but it will read as false once the renderer half lands. Worth a domain:spec-surface follow-up to make it mode-aware.

Gates

Run locally in the task worktree, all green: check:nul-bytes, check:role-word (44 baselined files, no new occurrences — the new prose avoids the ratcheted word), check:quick-reference-counts, check:doc-authoring, check:docs-audit-scope (incl. both self-tests; 179 hand-written docs in sync). Note: the card named check:doc-formula-expressions, which does not exist in package.json — the nearest existing doc-corpus gate, check:doc-authoring, was run instead. CI's full farm is authoritative.

Changeset

None. Docs-only diff touching no published package; the reader-visible behavior change belongs to the ObjectUI renderer half and should carry its changeset there, so a changeset here would announce a shipped change that has not shipped. skip-changeset at review.

Also observed, not fixed (kept the diff single-purpose)

The hand-written docs spell the console mount /console/forms/:name (9 occurrences across content/docs + skills/), while the measured live URL in #7245 is /_console/forms/... and protocol/objectui/actions.mdx:87 itself uses /_console/. Fixing 2 of 9 would make it worse; it wants its own docs-accuracy card.

Generated by Claude Code